/* Copyright (c) 2011 William Steven Knauer
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 * and associated documentation files (the "Software"), to deal in the Software without restriction,
 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all copies or
 * substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
 * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

package com.williamknauer.android.multitouchdetector;

/**
 * A listener used to notify when an event has been generated by a
 * MultitouchDetector. Intended to be used with a {@link MultitouchDetector}.
 * 
 * CHANGELOG:
 *     2011.0903 v1.0: Drag, scale, and tap functionality are working
 *                     with this listener.
 *     2011.0904 v1.1: Changed callbacks to use float parameters only. Added
 *                     more parameters to be more verbose about gestures as they
 *                     begin and end.
 * 
 * @author William S Knauer <knauerw1@gmail.com>
 * @version 2011.0904
 */
public interface MultitouchListener {

	/**
	 * Notifies when a drag gesture involving two pointers has occurred. This
	 * will be called each time a move event is handled by the
	 * MultitouchDetector until the drag gesture is finished as signaled by
	 * {@link onMultiDragEnd()}.
	 * 
	 * @param x1
	 *            The horizontal position of the primary pointer
	 * @param y1
	 *            The vertical position of the primary pointer
	 * @param x2
	 *            The horizontal position of the secondary pointer
	 * @param y2
	 *            The vertical position of the secondary pointer
	 * @param focusX
	 *            The horizontal focus of the two pointers
	 * @param focusY
	 *            The vertical focus of the two pointers
	 * @param dx
	 *            The horizontal distance dragged since the last call to this
	 *            method
	 * @param dy
	 *            The vertical distance dragged since the last call to this
	 *            method
	 * @return {@code true} if this event is handled
	 */
	public abstract boolean onMultiDrag(float x1, float y1, float x2, float y2, float focusX,
			float focusY, float dx, float dy);

	/**
	 * Notifies when a drag gesture involving two pointers has begun.
	 * 
	 * @param x1
	 *            The horizontal position of the primary pointer
	 * @param y1
	 *            The vertical position of the primary pointer
	 * @param x2
	 *            The horizontal position of the secondary pointer
	 * @param y2
	 *            The vertical position of the secondary pointer
	 * @param focusX
	 *            The horizontal focus of the two pointers
	 * @param focusY
	 *            The vertical focus of the two pointers
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onMultiDragBegin(float x1, float y1, float x2, float y2, float focusX,
			float focusY);

	/**
	 * Notifies when a drag gesture involving two pointers has finished.
	 * 
	 * @param x1
	 *            The horizontal position of the primary pointer
	 * @param y1
	 *            The vertical position of the primary pointer
	 * @param x2
	 *            The horizontal position of the secondary pointer
	 * @param y2
	 *            The vertical position of the secondary pointer
	 * @param focusX
	 *            The horizontal focus of the two pointers
	 * @param focusY
	 *            The vertical focus of the two pointers
	 * @param totalDistX
	 *            The total horizontal distance dragged
	 * @param totalDistY
	 *            The total vertical distance dragged
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onMultiDragEnd(float x1, float y1, float x2, float y2, float focusX,
			float focusY, float totalDistX, float totalDistY);

	/**
	 * Notifies when a two-finger scale/zoom gesture has occurred. This will be
	 * called each time a move event is handled by the MultitouchDetector until
	 * the drag gesture is finished as signaled by {@link onScaleEnd()}.
	 * 
	 * @param x1
	 *            The horizontal position of the primary pointer
	 * @param y1
	 *            The vertical position of the primary pointer
	 * @param x2
	 *            The horizontal position of the secondary pointer
	 * @param y2
	 *            The vertical position of the secondary pointer
	 * @param focusX
	 *            The horizontal focus of the two pointers
	 * @param focusY
	 *            The vertical focus of the two pointers
	 * @param scale
	 *            The change in scale since the last call to this method
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onScale(float x1, float y1, float x2, float y2, float focusX,
			float focusY, float scale);

	/**
	 * Notifies when a two-finger scale/zoom gesture has begun.
	 * 
	 * @param x1
	 *            The horizontal position of the primary pointer
	 * @param y1
	 *            The vertical position of the primary pointer
	 * @param x2
	 *            The horizontal position of the secondary pointer
	 * @param y2
	 *            The vertical position of the secondary pointer
	 * @param focusX
	 *            The horizontal focus of the two pointers
	 * @param focusY
	 *            The vertical focus of the two pointers
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onScaleBegin(float x1, float y1, float x2, float y2, float focusX,
			float focusY);

	/**
	 * Notifies when a two-finger scale/zoom gesture has finished.
	 * 
	 * @param x1
	 *            The horizontal position of the primary pointer
	 * @param y1
	 *            The vertical position of the primary pointer
	 * @param x2
	 *            The horizontal position of the secondary pointer
	 * @param y2
	 *            The vertical position of the secondary pointer
	 * @param focusX
	 *            The horizontal focus of the two pointers
	 * @param focusY
	 *            The vertical focus of the two pointers
	 * @param scale
	 *            The total change in scale
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onScaleEnd(float x1, float y1, float x2, float y2, float focusX,
			float focusY, float totalScale);

	/**
	 * Notifies when a single-pointer drag/scroll gesture has occurred. This
	 * will be called each time a move event is handled by the
	 * MultitouchDetector until the drag gesture is finished as signaled by
	 * {@link onSingleDragEnd()}.
	 * 
	 * @param x
	 *            The horizontal position of the pointer
	 * @param y
	 *            The vertical position of the pointer
	 * @param dx
	 *            The horizontal distance dragged since the last call to this
	 *            method
	 * @param dy
	 *            The vertical distance dragged since the last call to this
	 *            method
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onSingleDrag(float x, float y, float dx, float dy);

	/**
	 * Notifies when a single-pointer drag/scroll gesture has begun.
	 * 
	 * @param x
	 *            The horizontal starting position of the pointer
	 * @param y
	 *            The vertical starting position of the pointer
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onSingleDragBegin(float x, float y);

	/**
	 * Notifies when a single-pointer drag/scroll gesture has finished.
	 * 
	 * @param x
	 *            The horizontal position of the pointer
	 * @param y
	 *            The vertical position of the pointer
	 * @param totalDistX
	 *            The total horizontal distance dragged
	 * @param totalDistY
	 *            The total vertical distance dragged
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onSingleDragEnd(float x, float y, float totalDistX, float totalDistY);

	/**
	 * Notifies when a tap/clicked has occurred.
	 * 
	 * @param x
	 *            The horizontal position of the tap
	 * @param y
	 *            The vertical position of the tap
	 * @return {@code true} if the event is handled
	 */
	public abstract boolean onSingleTap(float x, float y);

}